Gold Medal Software 2/Gold Medal Software Volume 2 (Gold Medal) (1994).iso/prog/asm_n_z.arj/SIT.DOC

Text File | 1989-05-26 | 13KB | 394 lines

===== WHAT IS "SIT"?

  SIT is a utility program for creating, modifying or deleting
strings in the MS-DOS environment.  It overcomes some
limitations of the intrinsic MS-DOS SET command, and provides
additional features as well.


===== OKAY, SWELL.  WHAT IS "SET"??

  MS-DOS has an intrinsic command called SET for creating and
deleting environment strings.  ("Intrinsic" means that the
command is built into the DOS command interpreter program
COMMAND.COM, rather than existing as a separate program file.)

  However, there's a problem with SET -- it only works on the
_current_ copy of the environment strings.

  When you first boot up a PC with MS-DOS, a _master_copy_ of
COMMAND.COM is loaded into memory, and this copy creates a
_master_environment_ block.  Each time you run a program under
MS-DOS, COMMAND.COM makes a _new_copy_ of the environment
strings (in a separate memory block) that is used by the program
you run.

  SET modifies the _current_ copy of the environment.  When
you're sitting at the command prompt C>, the "current" copy _is_
the MASTER copy.

  However, when you run a .BAT file, COMMAND.COM creates a
"working" copy of the environment for use by that .BAT file --
and if the .BAT file has a SET command in it, it's the WORKING
copy that gets modified.

  That's great if the environment string you're creating or
modifying is used WITHIN the .BAT file, but if you want the new
environment value to be "permanent" (that is, you want your
changes to survive after the .BAT file terminates), you're out
of luck -- because COMMAND.COM discards the WORKING copy of the
environment strings when the .BAT file completes... and the
MASTER copy doesn't have the changes in it!


  SET is also pretty simple-minded about its syntax.

  If you type the command

      SET VOOTIE=SOMETHING

and then examine your environment (just type SET without
parameters), you'll see that you've got an entry that says the
variable "VOOTIE" is equal to the value "SOMETHING".  Enter

      SET VOOTIE=

and that entry will be cleared out of your environment.

  Now, if you throw in an extra space, _you_ might not notice,
but SET thinks you're talking about something entirely different!

      SET VOOTIE = SOMETHING

puts a variable called "VOOTIE " (note the trailing space!)
equal to the value " SOMETHING" (note the _leading_ space!)

  As far as MS-DOS is concerned, the environment variables
"VOOTIE" and "VOOTIE " are two completely different, unrelated
variable names (and may have completely different values as
well).  This can easily lead to confused programmers,
particularly when you've been debugging since half past
midnight...

  SIT trims the trailing spaces (between the variable name and
the "=" sign), so SET VOOTIE=SOMETHING and SET VOOTIE =SOMETHING
both apply to the environment variable VOOTIE.  However, (since
you may _want_ to embed spaces within the _value_) SIT treats
everything _after_ the "=" sign as significant:

          SET VOOTIE = SOMETHING    is not the same as
      SET VOOTIE =SOMETHING

            --
===== WHY IS "SIT" BETTER THAN "SET"?

  SIT lets you do everything SET does, but it does it to the
MASTER copy of the environment strings.

  SIT also trims trailing spaces off the names of environment
variables, so you don't accidentally create a new variable that
isn't what you thought it was. (See above.)

  SIT provides three new syntax forms that allow you to

      -- APPEND a string to the end of an existing value
      -- PREPEND a string to the beginning of an existing value
      -- REMOVE a substring from within an existing value

  Finally, SIT accepts one or more environment-variable
assignments from standard input.  This lets you redirect a text
file into SIT to make several assignments at once, or "pipe" the
output of a program into SIT.  For example, in my AUTOEXEC.BAT
file, I pipe the output of a program that reports the current
system date and time (in a special format) into SIT to set a
variable

      DATESTAMP=yymmdd

that is used by my program MAKE tool to automatically include
the date a program was assembled or compiled into the program
itself.  This helps to keep track of versions and changes.


===== WHY DO YOU CALL IT "SIT"?

  'Cuz I feel like it.  However,

  1) "SIT" is pretty close to "SET", which is good since they
      do the same kind of work.

  2) "sit" is a Latin verb, a form of the verb "esse" (to be).
      (Pluperfect imperative, I think.  Mrs. Ferguson, where
       the heck are you when I _need_ you???)

     "sit" means roughly "Let it be" or "Make it so" (with
       apologies to Capt. J.-L. Picard) which is a pretty good
       match to the command "set" (x equal to y).

     For example, the motto of the University of Washington is
       LUX SIT  ("Let there be light").  (The rumor that "Lux,
       sit!" is what the Husky cheerleaders say to the mascot
       is, of course, completely unfounded...)



===== FINE, YOU'RE A NERD IN THREE LANGUAGES.  HOW DO I USE IT?

SIT <variable>=<value>

    For example,

        SIT path=c:\;c:\bin

    will either create the variable PATH (if it doesn't
    already exist in the master environment) and assign
    it the value "c:\;c:\bin", or (if it already exists)
    change it from its previous value to "c:\;c:\bin".

    Notice that the name of the VARIABLE is forced to
    upper-case ("PATH" rather than "path")... but the
    VALUE keeps the case of the letters you type
    ("c:\;c:\bin" rather than "C:\;C:\BIN")

    Since SIT trims the trailing spaces off the variable
    name (which SET doesn't do),

        SIT   path    =c:\;c:\bin

    does the same thing as the first version.  HOWEVER,
    spaces AFTER the equals sign are significant!

        SIT path1  =  c:\; c:\bin

    sets the variable PATH1 to the value "  c:\; c:\bin"
    (notice the embedded spaces!)


SIT <variable>

    Reports the current value of VARIABLE, if it exists
    in the master environment.


SIT <variable>=

        Clears VARIABLE out of the master environment if it
    exists.

    Notice that the "=" must be the very last thing on the
    command line.  If you follow the "=" with one or more
    spaces, you are setting the value of VARIABLE to "  ".



(Enhanced syntax for SIT)--


SIT <variable>-=<value>

    Removes a substring from an existing value.  If
    VARIABLE exists in the master environment, SIT searches
    its value for the leftmost substring matching <value>
    and chops it out of the value.    For example, if you

            SIT ITEM =HUBBA HUBBA
            SIT ITEM -=UBB

    then the new value of ITEM is "HA HUBBA" (the second
    command removed the LEFTMOST letters "UBB").

    If VARIABLE does not exist, or if <value> is not a
    substring of an existing value, nothing happens.

    If the substring removed is the _entire_ existing value,
    SIT eliminates VARIABLE from the environment entirely.
    That is, it treats VARIABLE as though you had said

            SIT VARIABLE=

    If SIT did not remove the variable, it would leave it in
    the environment but with an empty value -- something that
    could be useful, but isn't the way SET works, so we won't
    work that way either.



SIT <variable>+=<value>

    Appends a substring to the END of an existing
    variable, or creates a new variable with the <value>.

    For example,

        SIT ITEM =HUBBA
        SIT ITEM +=DUBBA

    then the new value of ITEM is "HUBBADUBBA" (notice,
    no space!  If you wanted a space, you should have
    said

        SIT ITEM += DUBBA

    right?)

    If VARIABLE doesn't yet exist, SIT += does the same
    thing that SIT = does:

        SIT NEWVARIABLE +=BYE BYE BLACKBIRD

    (the value of NEWVARIABLE is "BYE BYE BLACKBIRD").



SIT <variable>&=<value>

    &= works like +=, except that it PREPENDS the substring
    <value> to the BEGINNING of an existing value. Example:

    SIT ITEM=HUBBA          (value is "HUBBA")
    SIT ITEM+=DUBBA        (value is "HUBBADUBBA")
    SIT ITEM-=HUBBA        (value is "DUBBA")
    SIT ITEM&=RUBBA     (value is "RUBBADUBBA")

    This is handy for doing things like adjusting your
    PATH.  For example,

    SIT PATH &=C:\LOTUS;

    will make MS-DOS look for commands first in the
    subdirectory you're in, then in C:\LOTUS, and finally
    in all the subdirectories that were already on the
    PATH... but it will search C:\LOTUS _before_ the
    old PATH subdirectories.



SIT

    all by itself accepts Standard Input and interprets it
    line-by-line as if you had typed each line on the SIT
    command line.  For example, you can type

           SIT

    You may then type lines into SIT and it will process
    them one by one

        path&=c:\lotus
        init+=d:\init;
        include-=d:\work\include;
        ^C

    [Ctrl-C], [Ctrl-Z] or [Ctrl-Break] will end the SIT
    session.  You might also have put those three lines
    into a text file called SITSETS.TXT and simply typed

        SIT <SITSETS.TXT

    to do the same thing.  Finally, you can pipe the
    output of another program into SIT:

        UDATE +'datestamp=/%y%m%d" | SIT

    causes the variable DATESTAMP to appear in the master
    environment with the value /890421 (assuming that
    today is April 21, 1989...)



==== CREDENTIALS

  I write programs for a living.  (Actually, I write programs
for fun, but my boss seems to get a kick out of giving me a
paycheck, so who am I to argue?)

  I also write programs for fun.  (See, I told you!)  And
sometimes I write programs that make it easier to write other
programs.  SIT is a program like that.

  I'm publishing SIT for the education of novice programmers,
the amusement of experienced programmers, and in the hopes that
it will someday save someone somewhere half a minute in a batch
file.  It's not particularly complicated, and I'm not looking
for a profit from SIT, so I'm placing it

             IN THE PUBLIC DOMAIN

which means you're free to do what you want with it -- modify
it, put it inside your own programs, or just have a good laugh
and forget about it.

  If you have any comments, suggestions or questions, you can
reach me at

          Davidson Corry
      4610 S.W. Lander St.
      Seattle, WA  98116
      [phone]

I don't guarantee to incorporate your ideas, agree with you or
even feel like talking, but usually I'm pretty mellow.
Hope you enjoy SIT.

                      -- Daí

5/26/89 update --

  After the original release of SIT, one of the foolhardy souls
who dared try it discovered that SIT did not work properly with
4DOS, the new (and excellent) shareware replacement for
COMMAND.COM.  Since I use COMMAND.COM exclusively (because of
some compatibility problems between 4DOS and Novell NetWare), I
didn't discover this.

  The problem lies in the way COMMAND.COM takes over some
interrupt vectors.  I assumed that the segment portion of the
INT 2Eh vector (the so-called "back door to COMMAND.COM") would
always point to the master copy of the shell in charge.  I could
then go looking for a memory block that was owned by that
segment and be confident it was my master environment segment.

  Turns out it doesn't work that way.  More exactly, COMMAND.COM
_does_ work that way, but 4DOS doesn't.  So, I modified the code
to look for the first memory block that "owns itself" -- that
is, the segment address of the arena header is one less than the
value of the "owner" PSP segment, found at offset [1] into the
arena header.  (Read Ray Duncan's _Advanced_MS-DOS_Programming_
if this doesn't make sense to you -- he explains DOS memory
allocation a lot better than I do...)

  Now that I can correctly find the shell-in-charge (be it 4DOS
or COMMAND.COM), I can then confidently look for a master
environment block...   and that turns out to be another can of
worms.

  By default, 4DOS does _not_ maintain a "master environment
block" -- instead, it keeps an _internal_ copy if you run 4DOS
in memory-resident mode, or swaps the environment out to EMS or
disk if you are running 4DOS in swapping mode.  Sigh.

  Starting with version 2.1, 4DOS allows you to specify a
COMMAND.COM-compatible master environment segment at boot time
(turns out there are _lots_ of programs that need to find the
master environment copy).  SIT has been modified to crap out
gracefully if it can't find the master environment copy. (The
original version just hangs your computer.  Nice, eh?)

  So...

==== IF YOU ARE USING SIT WITH 4DOS

  You must

  1) Use 4DOS version 2.1 (or later).  Version 2.0B and earlier
will _not_ work properly with SIT.

  2) Configure 4DOS in swapping mode and use the /M:nnnn switch
to set environment size, rather than the (default) /E:nnnn
switch -- read the 4DOS documents for details.

  -- or --

  Don't use SIT with 4DOS, and use 4DOS's capabilities to play
with your environment.